'\" t
.TH tagrelease 1 "20 April 2007" "Code Manager II"

.SH NAME
tagrelease \- Tag a project for a code release

.SH SYNOPSIS
.TS
l.
tagrelease  \fB--tag\fP \fITAG\fP \fB--desc\fP \fIMSG\fP [\fB--force\fP]
           [\fB--allow-open\fP] [\fB--verbose\fP] [\fB--force-write\fP]
           [\fB--nopretag\fP]
.TE

.SH DESCRIPTION
The \fPtagrelease(1)\fP utility is used to indicate that the current versions of all files
under code control have reached a logical 'check point'. Typically these check points are
used to define a usable level of software that can be used to generate a package
based on the project for subsequent installation on other machines.

However tags also serve in allowing changes both internally within the project over time,
and even changes between projects to be compared. 

More importantly tags are used when two projects are merged to work out the differences
between them and hence define the steps to take to allow the merge to take place.

Finally the \fIrollback(1)\fP tool uses tags to allow a code project to totally discard all 
changes following a specified tag - perminently.

.SH ARGUMENTS
.TP 8
.B --verbose
Show more information regarding the code tagging process.
.TP
.B --tag
This is a mandatory argument that is used to name the tag. The tag specified must not 
already exist for this project (though see the \fB--force\fP option), and must not contain
any special characters beyond ',','-' or '_'. White space is not well supported in tags, though
the tag length is not limited.
.TP
.B --desc
A mandatory short description indicating the purpose of the release. Obviously since the
parameter passed is likely to contain white space it should be inclosed in single or
double quotes.
.TP
.B --force
Forces the tag creation process to proceed even if the tag already exists. Without this
option the command will fail if the tag name exists for the project. Although the 
project transaction log is changed to reflect the re-use of the tag it should only be 
done when strictly required.
.TP
.B --force-write
Forces the tag creation when the current project has a \fBPROTECTION\fP setting
of "force-write". If such a \fBPROTECTION\fP setting is present, but this argument is
not specified then the tag creation will be aborted.
.TP
.B --allow-open
Usually if any file under the directories that are to be tagged is currently checked out
the tag creation will be aborted. If this argument is specified then the latest checked in
version of such files will be used.
.TP
.B --nopretag
Do not run the pretag script if it defined/exists.

.SH EXIT CODES
The \fItagrelease(1)\fP follows UNIX standard practise:

.TP 4
.B 0
The tag creation process completed successfully.
.TP
.B >0
An error occured whilst attempting to create the specified tag.

.SH NOTES

.SS Tag Files
Each tag is kept as a separate file in the code repository for the project. The size
of each tag is mainly determined by the number of files recorded in the tag. Older tags
can be manually removed from under the 'releases' directory if disk space becomes 
problematic - but this should not become common practise.

The names of the tags only need to be unique within the project itself - the same tag name
can be used over as many projects as necessary if so desired.

To successfully integrate with the software packaging features offered by \fBCode Manager II\fP
the tag should typically be in the form:

.TS
l.
major.minor.revision
.TE

In all cases the above items will be numbers, for example '1.2.3' or '0.2.0'. If a particular
project wishes to force a naming scheme for tags then the optional setting \fBTAGFMT\fP
can be used. This should be given a standard Perl pattern to ensure the tag conforms 
to it. For example consider the following popular setting:

.TS
l.
TAGFMT:^\d+\.\d+(\.\d+){1,}$
.TE

The above format allows numeric only tags with at least one period, and so
would allow tags should as 12.00 or 12.00.1 or 12.0.2.22323. 

.SH AUTHOR
The \fBCode Manager II\fP tool set was written by Simon Edwards, Proprius Consulting Ltd, (\fBwww.proprius.co.uk\fP).

.SH SEE ALSO
.BR cm2_cmpprojects(1),
.BR cm2_cmpreleases(1),
.BR cm2_cpproject(1),
.BR cm2_listreleases(1),
.BR cm2_rollback(1),
.BR cm2_tagremove(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP.

